fly: create GIF images on the fly

Obtaining fly

fly source code is available in the following formats:

unix tar, compressed:
fly.tar.Z (137k)
unix tar, GNU zipped:
fly.tar.gz (82k)
pkzip:
fly.zip (85k)

fly is a C program that creates GIF images on the fly from CGI and other programs. Using Thomas Boutell's gd graphics library for fast GIF creation, it provides a command-file interface for creating and modifying GIF images.

Current version: 1.41, 29th January 1997

Table of Contents

  1. Obtaining the source.
  2. Installing fly.
  3. How to use fly.
  4. Feedback.
  5. Fly on the Web.
  6. Mailing Lists.
  7. The Future.
  8. Bugs & FAQs.
  9. Contributors.
  10. Release notes.

Installing fly

If you have obtained fly.tar.Z or fly.tar.gz, enter the following commands at the unix prompt:

uncompress fly.tar.Z or gunzip fly.tar.gz
This will decompress the compressed archive.
tar xfv fly.tar
This will un-tar the archive, placing its contents in a directory called fly
cd fly; make
If all goes well, this will compile the program giving you an executable called fly

If you have obtained fly.zip, enter the following command at the DOS prompt:

pkunzip -d fly.zip
This will unzip the archive. Note: it is essential that you use the -d switch to force pkunzip to create the necessary directories.
You will need a C compiler (and possibly some experience) to compile fly.

If you have obtained the NT/Win95 zip file, fly-win.zip, enter the following command at the DOS prompt:

pkunzip -d fly.zip

This will unzip the archive.

If you have obtained the NT/Win95 binary, fly.exe, no installation is necessary.

If you obtained one of the precompiled binaries, enter the following commands:

gunzip fly.OS.tar.gz
tar xfv fly.OS.tar

Troubleshooting

If you are attempting to compile from source and don't have gcc, you will get an error message along the lines of 'gcc: command not found' and make will exit. Just change the lines in the Makefile and the Makefile in the gd1.2 directory that read:
CC = gcc
to:
CC = cc
and it should work. If it still doesn't compile, try one of the pre-compiled binaries, or contact me.

Using fly

Invoking fly

Note that the command line arguments for v1.1 and later are different from v1.0 and earlier.

The standard manner used to invoke fly is:
fly -i <input file> -o <output file>

You can omit the input file, and fly takes its directives from stdin, and if you omit the output file, the output goes to stdout.

The command file

The command file uses a number of directives. It must start with one of the following lines:

existing /path/to/file.gif
if modifying an existing image, OR
new
size x,y
for creating a new image of width x pixels, height y pixels.

After the initial command, any of the commands below may be used.

To create more than one image from a command file, use the directive end, followed by either

existing /path/to/file.gif
name <filename.gif>
if modifying an existing image, OR
new
size x,y
name <filename.gif>
for creating a new image.

Note:

Directives & explanations

line x1,y1,x2,y2,R,G,B
Creates a line from coordinates x1,y1 to coordinates x2,y2 of colour R,G,B.
dline x1,y1,x2,y2,R,G,B
Creates a dashed line from coordinates x1,y1 to coordinates x2,y2 of colour R,G,B.
rect x1,y1,x2,y2,R,G,B
Creates a rectangle from coordinates x1,y1 to coordinates x2,y2 with edging of colour R,G,B.
frect x1,y1,x2,y2,R,G,B
Creates a filled rectangle from coordinates x1,y1 to coordinates x2,y2 filled with colour R,G,B.
square x1,y1,s,R,G,B
Creates a square qith the top left corner at coordinates x1,y1, with side s in length, with edge of colour R,G,B.
fsquare x1,y1,s,R,G,B
Creates a square qith the top left corner at coordinates x1,y1, with side s in length, filled with colour R,G,B.
Creates a filled rectangle from coordinates x1,y1 to coordinates x2,y2 filled with colour R,G,B.
poly R,G,B,x1,y1...,xn,yn
Creates a polygon (has to be closed) through the points x1,y1 to x2,y2 to ... to xn,yn, of colour R,G,B.
Note that the colour values appear before the coordinates in this directive.
fpoly R,G,B,x1,y1...,xn,yn
Creates a polygon (has to be closed) through the points x1,y1 to x2,y2 to ... to xn,yn, filled with colour R,G,B.
Note that the colour values appear before the coordinates in this directive.
arc x1,y1,w,h,start,finish,R,G,B
Creates an arc of colour R,G,B centered at coordinates x1,y1, of width w and height h, starting at start degrees and finishing at finish degrees.
fcircle x1,y1,d,R,G,B
Creates a circle centered at coordinates x1,y1, of diameter d, filled with colour R,G,B.
circle x1,y1,d,R,G,B
Creates a circle of colour R,G,B centered at coordinates x1,y1, of diameter d.
fill x,y,R,G,B
Flood fills with the colour R,G,B from the coordinates x,y to the edge of the area of the original color of x,y.
filltoborder x,y,R1,G1,B1,R2,B2,G2
Flood fills with colour R2,G2,B2 from x,y to the border of colour R1,G1,B1.
string R,G,B,x,y,<size>,<string>
Writes a string starting at x,y (in the colour R,G,B), of font size <size>, where size can be one of tiny, small, medium, large or giant.
stringup R,G,B,x,y,<size>,<string>
Writes a string vertically starting at x,y (in the colour R,G,B), of font size <size>, where size can be one of tiny, small, medium, large or giant. The string will go up from the coordinates supplied.
copy x,y,x1,y1,x2,y2,filename.gif
Copies region x1,y1 - x2,y2 of filename.gif to the coordinates x,y of the image being created/modified.
If x1,y1,x2,y2 are all -1, copy the entire image.
copyresized x1,y1,x2,y2,dx1,dy1,dx2,dy2,filename.gif
Copies region x1,y1 - x2,y2 of filename.gif to the area dx1,dy1 - dx2,dy2 of the image being created/modified, resizing the image to fit.
If x1,y1,x2,y2 are all -1, copy the entire image.
getpixel x,y
Gets the colour index of the point at x,y.
setpixel x,y,R,G,B
Sets the point at x,y to the colour R,G,B.
setbrush filename.gif
Sets the current "brush" to filename.gif. Subsequent directives of line, dline, rect, poly and arc will use the selected "brush" to draw their lines, until a call of killbrush.
killbrush
Turns off the brush selection. Calls to line, dline, rect, poly and arc will then use the standard single-pixel width brush.
settile filename.gif
Sets the current "tile" to filename.gif. Subsequent directives of fill, filltoborder, and fpoly will use the selected "tile" as a fill pattern, until a call of killtile.
killtile
Turns off the tile selection. Calls to fill, filltoborder and fpoly will then use the specified colour for fills.
setstyle R1,G1,B1, R2, G2, B2, ..., Rn,Gn,Bn
Various line calls can use a style, specified by one or more colour settings for each pixel, that is repeated for the length of the "line". All subsequent directives of line, dline, rect, poly and arc will use the selected "style" to draw their lines, until a call of killstyle.
killstyle
Turns off the style selection. Calls to line, dline, rect, poly and arc will then use the standard single-pixel width brush.
transparent R,G,B
Makes the colour R,G,B the transparent colour.
sizex
Returns the width of the image in pixels.
sizey
Returns the height of the image in pixels.
interlace
Makes the image output by fly an interlaced GIF.

Comments in the command file

At any point in the command file, you can insert a comment line starting with "#".

Example: 

new
size 256,256
#
# start with a background fill
fill 1,1,255,255,255
#
# then a circle in the middle
circle 128,128,180,0,0,0
#
etc.

Examples

If you are using fly from within a CGI program, here are some examples:

Perl
#!/usr/local/bin/perl

$flyprog = "/usr/local/bin/fly";
$outfile = "temp.gif";

open(FLY,"| $flyprog -o $outfile ");
print FLY "new\n";
print FLY "size 256,256\n";
print FLY "fill 1,1,255,255,255\n";
print FLY "circle 128,128,180,0,0,0\n";
print FLY "fill 128,128,255,255,0\n";
print FLY "arc 128,128,120,120,0,180,0,0,0\n";
print FLY "circle 96,96,10,0,0,0\n";
print FLY "circle 160,96,10,0,0,0\n";
print FLY "fill 96,96,0,0,0\n";
print FLY "fill 160,96,0,0,0\n";
close(FLY);
csh
#!/bin/csh
# test out fly!

cat > /tmp/fly.$$ <<EOD
new
size 256,256
fill 1,1,255,255,255
circle 128,128,180,0,0,0
fill 128,128,255,255,0
arc 128,128,120,120,0,180,0,0,0
circle 96,96,10,0,0,0
circle 160,96,10,0,0,0
fill 96,96,0,0,0
fill 160,96,0,0,0
EOD

fly -i /tmp/fly.$$ -o test.gif
C
If you're using C, then you might as well use gd!!

 

The Future (otherwise known as a to-do list).

I'm currently porting fly to the Macintosh. It will be an XCMD that can be used from Hypercard, MacPerl, Frontier (I think), and anything else that can use XCMDs or XFCNs.

Bugs & Frequently Asked Questions

There is a bug in the polygon code in the gd library that causes blank 'streaks' on some occasions when drawing filled polygons. I am currently waiting on a bug fix for this from the author of gd.

If you're using fly with perl on Windows NT or Windows 95, this may be of interest to you: From: http://www.endcontsw.com/people/evangelo/Perl_for_Win32_FAQ.html 

7.3. How do I return a graphics file from a CGI script?

One of the big differences between UNIX and Win32 platforms is
that on Win32 there's a difference between text or ASCII files
and binary file. To return a graphics file, you need to specify
that the file is a binary file, and that the standard output
stream should accept binary data. Try something like this: 

    $MY_FILE_NAME = 'Penelope.jpg';
    $CHUNK_SIZE = 4096;

    open( MY_FILE, "<$MY_FILE_NAME" )
         or die( "Can't open $MY_FILE_NAME: $!\n" );

    print "Content-type: image/jpeg\r\n";
    print "\r\n";

    binmode( MY_FILE ); # These are crucial!
    binmode( STDOUT ); 

    while ( $cb = read( MY_FILE, $data, $CHUNK_SIZE ) )
    {
        print $data;
    }

    close( MY_FILE );